Deploying 3CX and Provisioning Settings via setupconfig.xml

Introduction

Launch and automatically configure 3CX by creating a pre-populated XML file. Simply input the answers to the questions that the 3CX command-line tool asks you into the XML and store the file either in the host or in cloud-init. 3CX parses it automatically and auto-configures your PBX. It’s also possible to include extensions, SIP Trunks and DIDs during installation.

Overview

The deployment process with setupconfig.xml works by placing the XML file on the machine to automatically configure 3CX during install:

Download this sample Setup Template XML file.
Modify the configuration in the XML file manually and fill in all required details.
Place the setupconfig.xml file on the host machine:

For Linux in: /etc/3cxpbx/setupconfig.xml .
For Windows in: C:\ProgramData\3CX\Data\setupconfig.xml .

Install 3CX. When 3CX is installed, the command line wizard checks the above locations for the XML file and if found, it automatically processes them.

💡 Tip: Instead of copying the file you can also use cloud-init by copying the contents of the XML and pasting them in the Advanced / User data section. Consider this example for Amazon AWS cloud-init.

Example of Cloud-init

To include setupconfig.xml in cloud-init, download and use this cloud-init sample below:

#!/bin/bash -e

mkdir -p /etc/3cxpbx

cat > /etc/3cxpbx/setupconfig.xml << "<EOF>"

<EOF>

apt-get update

dpkg-query -W -f='${Status}' sudo 2>/dev/null | grep -qF "ok installed" || apt-get -y install sudo

dpkg-query -W -f='${Status}' wget 2>/dev/null | grep -qF "ok installed" || apt-get -y install wget

dpkg-query -W -f='${Status}' gnupg2 2>/dev/null | grep -qF "ok installed" || apt-get -y install gnupg2

wget -O- https://repo.3cx.com/key.pub | gpg --dearmor | sudo tee /usr/share/keyrings/3cx-archive-keyring.gpg > /dev/null

echo "deb [arch=$(dpkg --print-architecture) by-hash=yes signed-by=/usr/share/keyrings/3cx-archive-keyring.gpg] http://repo.3cx.com/3cx bookworm main" | sudo tee /etc/apt/sources.list.d/3cxpbx.list

apt-get update

apt-get -y install 3cxpbx

Setupconfig.xml Εxplained

The setupconfig.xml is split in these sections:

<tcxinit> - Parameters for the initial phase of the PBX Configuration tool, e.g. license, backup file path, network settings, public IP, FQDN (3CX FQDN or Custom FQDN), hostname, local DNS, HTTP(S) ports, extension length, mail server, timezone, country and license info.
<extensions> - Add the extensions to create in this section.
<siptrunk> - Define SIP trunks and DIDs to deploy and add a subnode in <inboundrules> to create inbound routing associated with the DID of that SIP trunk.
<OutboundRules> - Add outbound rules to create in this section.

Configuring the Wizard

This is an example XML subset that corresponds to the questions asked in the First-time Configuration wizard:

<option> <code>NumberOfExtensions</code> <answer>3</answer> </option>

<option> <code>MailServerType</code> <answer>3CX</answer> </option>

<option> <code>MailServerAddress</code> <answer>smtp.example.com</answer> </option>

<option> <code>MailServerReplyTo</code> <answer>[email protected]</answer> </option>

<option> <code>MailServerUserName</code> <answer>username</answer> </option>

<option> <code>MailServerPassword</code> <answer>password</answer> </option>

<option> <code>MailServerEnableSslTls</code> <answer>yes</answer> </option>

<option> <code>Continent</code> <answer>North America</answer> </option>

<option> <code>Country</code> <answer>United States</answer> </option>

<option> <code>Timezone</code> <answer>9</answer> </option>

<option> <code>OperatorVoicemail</code> <answer>999</answer> </option>

<option> <code>Promptset</code> <answer>English</answer> </option>

<option> <code>LicenseContactName</code> <answer>John L. Doe</answer> </option>

<option> <code>LicenseCompanyName</code> <answer>My Company Ltd.</answer> </option>

<option> <code>LicenseEmail</code> <answer>[email protected]</answer> </option>

<option> <code>LicensePhone</code> <answer>+357 987654321</answer> </option>

<option> <code>ResellerId</code><answer></answer> </option>



To populate Country and Timezone refer to this document and select values from the appropriate columns. For example, to specify Mexico based on the list you can use this configuration:

<option> <code>Country</code> <answer>Mexico</answer> </option>

<option> <code>Timezone</code> <answer>5</answer> </option>



Adding Extensions, SIP Trunks, DIDs and Outbound Rules

Use the <extensions> section to:

Add extensions, SIP trunks, inbound and outbound rules to the setup configuration file.
Provision an IP phone to an extension by configuring the relevant XML node with the appropriate info, from the Available Codec Values and Phone Templates for Supported IP Phones guide.

For example, to provision a Snom 720 phone, locate the model in the guide and note the corresponding supported codecs and template file name, i.e. snom.ph.xml. Enter this information in the corresponding XML tags in your setupconfig.xml file.

Creating an Extension

To automatically create and configure a new extension, add the info in an <extension> node under the <extensions> section:

<extension>

<LastName>Smith</LastName>

<EmailAddress>[email protected]</EmailAddress>

<AuthPassword>extensionPassword</AuthPassword>

<AllowLanOnly>false</AllowLanOnly>

<RecordCalls>false</RecordCalls>

<MAC>121212ABABAB</MAC>

</Codecs>

<Language>English</Language>

<ProvisionType>LocalLan</ProvisionType>

<AllowOwnRecordings>false</AllowOwnRecordings>

</extension>

Creating a SIP Trunk, DIDs and Inbound rules

To automatically create a SIP trunk, as well as its DIDs and inbound rules, add the relevant info in a <siptrunk> node based on this XML example excerpt:

<siptrunk>

<Name>Voip Trunk 1</Name>

<TemplateFilename>GenericSIPTrunk.pv.xml</TemplateFilename>

<Host>trunk.example.com</Host>

<ProxyHost>proxy.trunk.example.com</ProxyHost>

<RequireRegistrationFor>InOutCalls</RequireRegistrationFor>

<AuthPassword>sgh88DMVU6Uz60MQzwvF</AuthPassword>

<SeparateAuthPassword>3WayPass</SeparateAuthPassword>

<OfficeHoursDestinationType>Extension</OfficeHoursDestinationType>

<OutOfOfficeHoursDestinationType>Extension</OutOfOfficeHoursDestinationType>

<SupportReinvite>false</SupportReinvite>

<SupportReplaces>false</SupportReplaces>

<EnableSRTP>false</EnableSRTP>

<IPInRegistrationContact>Default</IPInRegistrationContact>

<codec>Speex</codec>

</Codecs>

<Name>IncomingCall1</Name>

<OfficeHoursDestinationType>Extension</OfficeHoursDestinationType>

<OutOfOfficeHoursDestinationType>Extension</OutOfOfficeHoursDestinationType>

</InboundRule>

</InboundRules>

</siptrunk>

Creating Outbound Rules with Backup Routes

In the <OutboundRules> section, you can add <OutboundRule> nodes to automatically create outbound rules and backup routes via your setupconfig.xml:

<OutboundRules>

<Name>Outbound Rule 1</Name>

</DNRange>

</DNRange>

</DNRanges>

<Group>Sales</Group>

</DNGroups>

<Gateway>GatewayIn</Gateway>

</OutboundRoute>

<Gateway>Trunk1a</Gateway>

</OutboundRoute>

</OutboundRoutes>

</OutboundRule>

</OutboundRules>

Importing SSL Certificates

To include SSL certificate information in your setupconfig.xml, use the below example to configure the parts relevant to SSL:

<option>

<code>NeedFqdn</code>

</option>

<code>FullExternalFqdn</code>

<answer>demo.3cx-example.com</answer>

</option>

<code>CertificatePath</code>

-----BEGIN PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAloremipsumdolorsita

...

cepteurSintoccaecatcupidatatnonproidentsuntinculpaquiofficiaDese

runtmollitanimidestlaborumQwIDAQAB

-----END PUBLIC KEY-----

</answer>

</option>

<code>CertificatePassword</code>

</option>

<code>CertificateKey</code>

-----BEGIN RSA PRIVATE KEY-----

MIIEowIBAAKCAQEAloremipsumdolorsitametconsecteturadipiscingelits

eddoeiusmodtemporincididuntutlaboreetdoloremagnamaliquautenimadm

...

inreprehenderitinvoluptatevelitEsSecillumdoloreEufugiatnullapari

aturExcepteurSintoccaecatcupidaTatnonproidentsuntinculpaquioffic

iadeseruntmollitanimidestlaboruM==

-----END RSA PRIVATE KEY-----

</answer>

</option>

<code>CertificateKeyPasswordRequest</code>

</option>



📄 Note: Different types of certificates require different XML nodes to be configured. Though CertificatePath is used in all, CertificatePassword is used only for pfx.

New Installation vs Restoring a Backup

To create a fresh 3CX installation, just set InstallationType=new and provide your Licence Key as shown below.

<tcxinit>

<code>InstallationType</code>

</option>

<code>LicenseKey</code>

</option>

</tcxinit>



In case you want to restore an existing backup via setupconfig.xml, set InstallationType=restore and provide the path to your backup file in BackupFile code.

Note: It can be an actual physical path on the local machine or an http link. In case your backup is encrypted, enter the backup password in the answer of BackupPassword code.

<tcxinit>

<code>InstallationType</code>

<answer>restore</answer>

</option>

<code>LicenseKey</code>

</option>

<code>BackupFile</code>

<answer>/var/tmp/mybackup.zip</answer>

</option>

<code>BackupPassword</code>

</option>

</tcxinit>

Setting Up the System Owner and Credentials

When configuring the xml, you’ll need to provide a list of extensions for your system. The first extension you configure will be assigned the System Owner Role.

<extensions>

<LastName>Smith</LastName>

<EmailAddress>[email protected]</EmailAddress>

...

<Name>SERVICES_ACCESS_HASH</Name>

<Value>AAAAAMAnCQAQAAAAAQ92DLZ6nqkahROS…KHRMtydHb8BsLA==</Value>

<ParameterType>String</ParameterType>

</CustomParameter>

</CustomParameters>

</extension>

<FirstName>Joanne</FirstName>

<LastName>Davis</LastName>

<EmailAddress>[email protected]</EmailAddress>

...

</extension>

...

Configuring your PBX Ports

Specify the ports that your PBX will use for HTTPS, HTTP, SIP and the 3CX tunnel in the following fields.

<tcxinit>

<code>HttpsPort</code>

</option>

<code>HttpPort</code>

</option>

<code>SipPort</code>

</option>

<code>TunnelPort</code>

</option>

…

</tcxinit>

Setting Up your Mail Server

To configure your PBX to use the 3CX SMTP server to send emails, set the following code in your xml:

<tcxinit>

<code>MailServerType</code>

</option>

</tcxinit>



To configure your PBX to use the Custom SMTP server to send emails, set the following code in your xml:

<tcxinit>

<code>MailServerType</code>

<answer>Custom</answer>

</option>

<code>MailServerAddress</code>

<answer>my-smtp.example.com</answer>

</option>

<code>MailServerReplyTo</code>

<answer>[email protected]</answer>

</option>

<code>MailServerUserName</code>

<answer>mySMTPUsername</answer>

</option>

<code>MailServerPassword</code>

<answer>mySMTPPassword</answer>

</option>

<code>MailServerEnableSslTls</code>

</option>

</tcxinit>

Public IP Configuration

The following code controls the configuration of the public IP of your PBX. Public IP code can be set to either auto for the PBX to auto-detect your public IP, or to manual if you want to manually configure the public IP of your PBX.

If you select manual, the ManualPublicIP code must then be populated with your PBX public IP as shown below, otherwise skip this code. For StaticOrDynamicIP code must be set to either static or dynamic.

Set to static in case you have a static IP address from your provider where it never changes.

Otherwise, set to dynamic so the PBX will periodically check for IP changes and adjust configuration and DNS records accordingly.

<tcxinit>

<code>PublicIP</code>

<answer>[auto|manual]</answer>

</option>

<code>ManualPublicIP</code>

</option>

<code>StaticOrDynamicIP</code>

<answer>[static|dynamic]</answer>

</option>

</tcxinit>

Local IP Configuration

The following code controls the configuration of your local interface/IP used by your PBX LocalIP code can be set to auto or manual.

If set to auto, the PBX will automatically take the first IP on the machine’s network stack. Note that in case your machine is not behind a NAT then the public IP will be taken.

In case your machine has multiple nic. adapters, you can set LocalIP to manual and populate the ManualLocalIP code with the local IP Address that you want your PBX to use.

Otherwise, skip this code.

<tcxinit>

<code>LocalIP</code>

<answer>[auto|manual]</answer>

</option>

<code>ManualLocalIP</code>

</option>

</tcxinit>

Using 3CX FQDNs

To configure your PBX to use 3CX FQDNs you need to use the following codes in the setupconfig.xml. Set NeedFqdn to yes to allow the PBX to create your chosen 3CX FQDN, certificates and DNS records. Only set to no if you plan to use your own custom FQDNs where you’ll need to upload your own custom certificates and manage your own DNS records.

Hostname must be populated with the preferred hostname of your FQDN. For example, it can be your company name. You should skip this if you set NeedFqdn to no, DomainGroup and DnsSuffix control the domain name to be used for your FQDN.

For example, the following configuration will install the PBX using example.3cx.eu as the FQDN.

<tcxinit>

<code>NeedFqdn</code>

</option>

<code>Hostname</code>

<answer>example</answer>

</option>

<code>DomainGroup</code>

<answer>Europe</answer>

</option>

<code>DnsSuffix</code>

</option>

</tcxinit>



Available Domain Group: Africa, Asia, Cities, Continent, Europe, Oceania, Other, South America, United States.

A list of all available suffixes per Domain Group that can be used when creating 3CX FQDNs can be found here.

Configuring a Different Local FQDN

By default, the PBX is installed in split DNS mode where, if the network is configured correctly, the 3CX FQDN must be fully resolvable on the LAN as well as outside of the LAN. This means your own DNS server or a firewall should be able to do hairpin nat.

In case you have a managed DNS, there is also the option to configure a different local FQDN to be used by local parties.

To do so you will need to set HasLocalDns code to yes and InternalFqdn code to your local internal FQDN.

<tcxinit>

<code>HasLocalDns</code>

</option>

<code>InternalFqdn</code>

</option>

</tcxinit>

Setting Up your PBX Language, Country, Time Zone and Prompt Sets

Language code controls the Language of the PBX (used for welcome emails, reports, etc.).

Prompt Set code controls the prompt set to be used in Voicemail Menus, IVRs, Queues, etc.

Country code is used for allowing calls to your country and for E164 Formatting. Timezone code controls the timezone used by the PBX.

<tcxinit>

<code>Language</code>

</option>

<code>Promptset</code>

<answer>English</answer>

</option>

<code>Country</code>

<answer>United States</answer>

</option>

<code>Timezone</code>

</option>

</tcxinit>



The available languages that can be used for the PBX are the following:

EN = English (US)
UK = English (UK)
DE = German
FR = French
ES = Spanish
IT = Italian
PT = Portuguese
RU = Russian
PL = Polish
ZH = Chinese

The available prompt sets that can be used can be found here

The available Countries and timezone codes that can be used can be found here

Whitelist/Blacklist of IPs

You can use the following example in your setupconfig.xml to whitelist/blacklist a single IP or a range of IPs / subnet.

Notice that the parent element of <IpBlackList> is the <SetupConfig>.

You can use Mask to declare a single IP Address (255.255.255.255) or to declare a whole subnet (eg. 255.255.0.0).

Set Allowed to true to whitelist the IP address or set to false to blacklist it.

<SetupConfig>

<Description>Single IP Allowed</Description>

</IpBlackListEntry>

<Allowed>false</Allowed>

<Description>Range of IPs Denied</Description>

</IpBlackListEntry>

</IpBlackList>

</SetupConfig>

Configuring Countries for Outbound Calls

You can use NOTALLOWED_COUNTRYCODES custom parameter in your setupconfig.xml to specify to which countries the PBX should allow outbound calls to be made to or not.

Note that the parent element of <CustomParameters> is the <SetupConfig>.

<CustomParameters>

<Name>NOTALLOWED_COUNTRYCODES</Name>

<ParameterType>String</ParameterType>

<Description>Specifies the country codes which are not allowed for outbound calls</Description>

</CustomParameter>

</CustomParameters>



Note that the value in the xml above holds the codes of the NOT ALLOWED countries. So in the example above where <value> is empty, outbound calls will be allowed to ALL countries.

In certain cases, it’s more useful to allow outbound calls to specific countries only. In this case, the following example can be used, where all available country codes are included. Just make sure to only remove the codes of the countries that you actually want to allow outbound calls to be made to.

<CustomParameters>

<Name>NOTALLOWED_COUNTRYCODES</Name>

<ParameterType>String</ParameterType>

<Description>Specifies the country codes which are not allowed for outbound calls</Description>

</CustomParameter>

</CustomParameters>



Deploying 3CX and Provisioning Settings via setupconfig.xml

Introduction

Overview

Example of Cloud-init

Setupconfig.xml Εxplained

Configuring the Wizard

Adding Extensions, SIP Trunks, DIDs and Outbound Rules

Creating an Extension

Creating a SIP Trunk, DIDs and Inbound rules

Creating Outbound Rules with Backup Routes

Importing SSL Certificates

New Installation vs Restoring a Backup

Setting Up the System Owner and Credentials

Configuring your PBX Ports

Setting Up your Mail Server

Public IP Configuration

Local IP Configuration

Using 3CX FQDNs

Configuring a Different Local FQDN

Setting Up your PBX Language, Country, Time Zone and Prompt Sets

Whitelist/Blacklist of IPs

Configuring Countries for Outbound Calls

See also

20 Years of VoIP
Industry Leadership

Company

Solutions

Useful Links

Learn More

20 Years of VoIP
Industry Leadership

Company

Solutions

Useful Links

Learn More

Deploying 3CX and Provisioning Settings via setupconfig.xml

Introduction

Overview

Example of Cloud-init

Setupconfig.xml Εxplained

Configuring the Wizard

Adding Extensions, SIP Trunks, DIDs and Outbound Rules

Creating an Extension

Creating a SIP Trunk, DIDs and Inbound rules

Creating Outbound Rules with Backup Routes

Importing SSL Certificates

New Installation vs Restoring a Backup

Setting Up the System Owner and Credentials

Configuring your PBX Ports

Setting Up your Mail Server

Public IP Configuration

Local IP Configuration

Using 3CX FQDNs

Configuring a Different Local FQDN

Setting Up your PBX Language, Country, Time Zone and Prompt Sets

Whitelist/Blacklist of IPs

Configuring Countries for Outbound Calls

See also

20 Years of VoIP Industry Leadership

Company

Solutions

Useful Links

Learn More

20 Years of VoIP Industry Leadership

Company

Solutions

Useful Links

Learn More

Cookie Preferences

20 Years of VoIP
Industry Leadership

20 Years of VoIP
Industry Leadership